home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / options.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  8.2 KB  |  228 lines
  1. .Na "options" 
  2. .Aa
  3. .Fu
  4. The complete list of \*L options.
  5. .Ih "options, list of"
  6. .Ih "\*L options, list of"
  7. .Sy
  8. .Si "<sybfront.h>"
  9. .Si "<sybdb.h>"
  10. .Co
  11. .Bl
  12. \f2dbsetopt()\f1 and \f2dbclropt()\f1 use the
  13. following constants, defined in \f2sybdb.h\f1, for setting and
  14. clearing options.
  15. .Ih "sybdb.h"
  16. All options are off by default.
  17. These options are available:
  18. .Bz
  19. .in +.375i
  20. .Pi DBPARSEONLY
  21. .Ih "DBPARSEONLY option"
  22. If this option is set, the \*S will only check the syntax of the query and return
  23. error messages to the host.  
  24. Offsets will be returned if the DBOFFSET option
  25. is set and there are no errors.
  26. .Pi DBSHOWPLAN
  27. .Ih "DBSHOWPLAN option"
  28. If this option is set, the \*S will generate a description of the processing plan after
  29. compilation and continue executing the query.
  30. .Pi DBNOEXEC
  31. .Ih "DBNOEXEC option"
  32. If this option is set, the \*S will process the query through the compile step but the
  33. query will not be executed.  This can be used in conjunction with
  34. .I DBSHOWPLAN.
  35. .Pi DBARITHABORT
  36. .Ih "DBARITHABORT option"
  37. .Ih "arithmetic exceptions"
  38. If this option is set, the \*S will abort a query when an arithmetic exception occurs during its execution.
  39. .mc |
  40. .Pi DBARITHIGNORE
  41. .Ih "DBARITHIGNORE option"
  42. If this option is set, the \*S will substitute null values for selected or updated values
  43. when an arithmetic exception occurs during query execution.
  44. The \*S will not return a warning message.
  45. If neither DBARITHABORT nor DBARITHIGNORE
  46. is set, \*S will substitute null values and print a warning
  47. message after the query has been executed.
  48. .Pi DBNOCOUNT
  49. .Ih "DBNOCOUNT option"
  50. This option causes \*S to stop sending back information about the number of
  51. rows affected by each SQL statement.
  52. The application can otherwise obtain this
  53. information by calling \f2DBCOUNT().\f1
  54. .Ih DBCOUNT
  55. .Pi DBTEXTSIZE
  56. .Ih "DBTEXTSIZE option"
  57. .Ih "text values, limiting the size of"
  58. .Ih "image values, limiting the size of"
  59. This option causes \*S to limit the size of returned text or image values.
  60. When setting this option, you supply a parameter which is the
  61. length, in bytes, of the longest text or image value that \*S
  62. should return.
  63. Note that, in programs that allow application users to make ad hoc queries,
  64. the user may override this option with the \*N SET TEXTSIZE
  65. command.
  66. To set a text limit that the user cannot override, use the DBTEXTLIMIT
  67. option instead.
  68. .mc
  69. .Pi DBOFFSET
  70. .Ih "DBOFFSET option"
  71. .Ih "\*N constructs, checking for"
  72. .Ih "offsets to \*N constructs"
  73. This option indicates where \*S should return offsets to certain constructs
  74. in the query.  DBOFFSET takes a parameter that specifies the 
  75. particular construct.  The valid parameters for this option are
  76. ``select'', ``from'', ``table'', ``order'', ``compute'', ``statement'', ``procedure'', ``execute'', or ``param''.
  77. (Note that ``param'' refers to parameters of stored procedures.)
  78. Calls to routines such as \f2dbsetopt()\f1 can specify these
  79. option parameters in either lower or upper case.
  80. For the internal types that correspond to the offsets, see 
  81. .I "dbgetoff()."
  82. Offsets are returned only if the batch contains no syntax errors.
  83. .Pi DBSTAT
  84. .Ih "DBSTAT option"
  85. .Ih "performance statistics"
  86. .Ih "statistics, performance"
  87. This option
  88. determines when performance statistics (CPU time, elapsed time, I/O, etc.)
  89. will be returned to the host after each query.
  90. DBSTAT takes one of two parameters:
  91. ``io'',
  92. for statistics about \*S internal I/O; and
  93. ``time'',
  94. for information about
  95. \*S's parsing, compilation, and execution times.
  96. These statistics are received by \*L in the form of informational
  97. messages, and application programs can access them through the
  98. user-supplied message handler.
  99. .Pi DBSTORPROCID
  100. .Ih "DBSTORPROCID option"
  101. .Ih "stored procedure"
  102. If this option is set, \*S will send the stored procedure id
  103. to the host before sending rows generated by the stored procedure.
  104. .Pi DBROWCOUNT
  105. .Ih "DBROWCOUNT option"
  106. .Ih "results rows, setting a maximum number"
  107. .Ih "rows, setting a maximum number"
  108. If this option is set, the \*S will return only a maximum specified number of regular rows 
  109. for SELECT statements.
  110. This option does not limit the number of compute rows returned.
  111. .sp 0.5v
  112. DBROWCOUNT works somewhat differently from most options.  It is always
  113. set on, never off.  Setting 
  114. DBROWCOUNT to 0
  115. sets it back to the default\(emthat is, to return all the rows generated by a
  116. SELECT statement.
  117. Therefore, the way to turn DBROWCOUNT
  118. .I off
  119. is to set it
  120. .I on
  121. with a count of  0.
  122. .Pi DBBUFFER
  123. .Ih "DBBUFFER option"
  124. .Ih "row buffering"
  125. .Ih "buffering rows"
  126. This option allows the application to buffer result rows, so that it
  127. can access them non-sequentially via the \f2dbgetrow()\f1 function.
  128. This option is handled locally by \*L and is not
  129. a \*S option.  When the option is set, you supply a parameter which
  130. is the number of rows you want buffered.
  131. If you use 0
  132. as the number of rows to buffer,
  133. the buffer will be set to a default size (currently 1000).
  134. .sp 0.5v
  135. Row buffering provides a way to keep a specified number of \*S result rows in program memory.
  136. Without row buffering, the result row generated by each new \f2dbnextrow()\f1 call overwrites the contents
  137. of the previous result row.
  138. Row buffering is therefore useful for programs that need to look at result rows 
  139. in a non-sequential manner.
  140. It does, however, carry a memory and performance penalty because each row in the buffer
  141. must be allocated and freed individually.
  142. Therefore, use it only if you need to.
  143. Specifically, the application should only turn the DBBUFFER option on if it calls \f2dbgetrow()\f1.
  144. Note that row buffering has nothing to do with network buffering and is a completely independent issue.
  145. (See 
  146. .I "dbgetrow(), dbnextrow(),"
  147. and
  148. .I "dbclrbuf()"
  149. for more information about row buffering.)
  150. .Pi DBNOAUTOFREE
  151. .Ih "DBNOAUTOFREE option"
  152. .Ih dbfreebuf
  153. .Ih "command buffer, clearing"
  154. This option causes the command buffer to be cleared only by an
  155. explicit call to \f2dbfreebuf()\f1.
  156. When DBNOAUTOFREE is \f2not\f1 set,
  157. after a call to \f2dbsqlexec()\f1 or \f2dbsqlsend()\f1
  158. the first call to either \f2dbcmd()\f1 or \f2dbfcmd()\f1 
  159. automatically clears the command buffer before the new text is entered.
  160. .mc |
  161. .Pi DBTEXTLIMIT
  162. .Ih "DBTEXTLIMIT option"
  163. .Ih "text values, limiting the size of"
  164. .Ih "image values, limiting the size of"
  165. This option causes \*L to limit the size of returned text
  166. or image values.
  167. When setting this option, you supply a parameter which is the
  168. length, in bytes, of the longest text or image value that your
  169. program can handle.
  170. \*L will read but ignore any part of a text or image
  171. value that goes over this limit.
  172. In the case of huge text values, it may take some time for
  173. the entire text value to be returned over the network.
  174. To keep \*S from sending this extra text in the first place,
  175. use the DBTEXTSIZE option instead.
  176. .mc
  177. .Kg
  178. .in -.375i
  179. .mc |
  180. .Bl
  181. DBBUFFER, DBNOAUTOFREE, and DBTEXTLIMIT are \*L options.
  182. That is, they affect \*L but are not sent to the \*S.
  183. The other options are \*S options\(emthey get sent to the \*S.
  184. \*S options are also settable through \*N.
  185. .Bl
  186. As mentioned in the preceding descriptions, certain 
  187. options take parameters:
  188. .nf
  189. .sp
  190. .ne 10
  191. .in +3n
  192. .ta +21n 
  193. \f3Option    Possible parameter values\f1
  194. .sp 0.5v
  195. DBTEXTSIZE    ``0'' to ``2,147,483,647''
  196. .sp .1v
  197. DBOFFSET    ``select'', ``from'', ``table'', ``order'', ``compute'', ``statement'', 
  198.     \0\0``procedure'', ``execute'', or ``param''
  199. .sp .1v
  200. DBSTAT    ``io'' or ``time''
  201. .sp .1v
  202. DBROWCOUNT    ``0'' to ``2,147,483,647''
  203. .sp .1v
  204. DBBUFFER    ``0'' to either ``32,767'' or ``2,147,483,647'', depending on whether 
  205.     \0\0your \f2int\f1 datatype is 2 or 4 bytes long
  206. .sp .1v
  207. DBTEXTLIMIT    ``0'' to ``2,147,483,647''
  208. .in -3n
  209. .sp
  210. .fi
  211. \f2dbsetopt()\f1 requires that an option
  212. parameter be specified when setting any option on the preceding list.
  213. \f2dbclropt()\f1 and \f2dbisopt()\f1 require that the parameter be specified only for 
  214. DBOFFSET and DBSTAT.  This is because DBOFFSET and DBSTAT
  215. are the only options that can have multiple settings at a time, and thus they require further
  216. definition before being cleared or checked.
  217. .sp 0.5v
  218. Note that parameters specified in calls to \f2dbsetopt()\f1, \f2dbclropt()\f1, and
  219. \f2dbisopt()\f1 are always passed as character strings and must be quoted,
  220. even if they are numeric values.
  221. See the \f2dbsetopt()\f1 manual page for more information.
  222. .Bz
  223. .mc
  224. .Sa
  225. dbclropt,
  226. dbisopt,
  227. dbsetopt
  228.